<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.3" />
<title>WebROaR User Guide</title>
<style type="text/css">
/* Sans-serif font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
div#toctitle,
span#author, span#revnumber, span#revdate, span#revremark,
div#footer {
  font-family: Arial,Helvetica,sans-serif;
}

/* Serif font. */
div.sectionbody {
  font-family: Georgia,"Times New Roman",Times,serif;
}

/* Monospace font. */
tt {
  font-size: inherit;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  font-size: inherit;
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
}

div#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(3);}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>WebROaR User Guide</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_introduction">1. Introduction</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="http://webroar.in">WebROaR</a> is an application server that makes deployments of
ruby web applications extremely simple. It provides an integrated solution to
view the run time performance numbers and sends email notifications in case any
exceptions occur in any of the deployed applications.</p></div>
<div class="paragraph"><p>It is 5 to 55% faster than all other comparable deployment stacks for
Ruby on Rails applications.</p></div>
<div class="sect2">
<h3 id="_key_features">1.1. Key Features</h3>
<div class="ulist"><ul>
<li>
<p>
Maximum Performance.
</p>
</li>
<li>
<p>
Simplified Deployment.
</p>
</li>
<li>
<p>
Runs Ruby on Rails&#8482; as well as other Rack compliant applications.
</p>
</li>
<li>
<p>
Run Multiple Applications Simultaneously.
</p>
</li>
<li>
<p>
Implements HTTP/1.1 grammar as per RFC 2616 including support for persistent,
 and chunked requests.
</p>
</li>
<li>
<p>
Intelligent load balancing and dynamic reaping of stuck ruby processing
 instances.
</p>
</li>
<li>
<p>
Provides run time performance data for the deployed applications.
</p>
</li>
<li>
<p>
Generates notifications in case any exceptions occur in any of the deployed
 applications.
</p>
</li>
<li>
<p>
Zero Downtime Application Upgrades.
</p>
</li>
<li>
<p>
Static assets encoding.
</p>
</li>
<li>
<p>
SSL support.
</p>
</li>
</ul></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_supported_operating_systems">2. Supported Operating Systems</h2>
<div class="sectionbody">
<div class="paragraph"><p>WebROaR has been tested on Ubuntu 8.10/9.04/9.10/10.04/10.10/11.04,
Debian 5 (64 Bit), Mac OS X (v10.5 &amp; v10.6), Arch Linux 2009.08 and Cent OS 5.2.
Basically, it should be able to run on any *IX OS.</p></div>
<div class="paragraph"><p>Currently it does not support Microsoft&#174; Windows.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_install">3. Install</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_prerequisites">3.1. Prerequisites</h3>
<div class="ulist"><ul>
<li>
<p>
ruby 1.8.x or 1.9.x
</p>
</li>
<li>
<p>
ruby 1.8-dev or 1.9-dev
</p>
</li>
<li>
<p>
openssl ruby extension (On Ubuntu/Debian it is available as libopenssl-ruby1.X)
</p>
</li>
<li>
<p>
zlib ruby extension
</p>
</li>
<li>
<p>
rubygems 1.3.6 or later
</p>
</li>
<li>
<p>
C build tools (gcc etc) (e.g. build-essential on Ubuntu, Xcode on MacOS)
</p>
</li>
<li>
<p>
libsqlite3
</p>
</li>
<li>
<p>
libsqlite3-dev
</p>
</li>
<li>
<p>
gnutls 2.4.1 or later (Only necessary in case SSL support is required)
</p>
</li>
<li>
<p>
gnutls-dev 2.4.1 or later (Only necessary in case SSL support is required)
</p>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_procedure">3.2. Procedure</h3>
<div class="paragraph"><p>WebROaR can be installed through its gem or directly from its source code. One
can also use Capistrano to perform a non-interactive installation of the
server.</p></div>
<div class="sect3">
<h4 id="_install_using_gem">3.2.1. Install using gem</h4>
<div class="paragraph"><p>WebROaR can be installed using the following commands:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo gem install webroar
sudo webroar install</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="title">SSL Support</div>
<div class="paragraph"><p>In case you would like to setup SSL support for the server, use the following
command line switch with <strong>sudo webroar install</strong> command mentioned above.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar install --ssl-support</tt></pre>
</div></div>
<div class="paragraph"><p>Configure further SSL options in the server&#8217;s admin panel
        <strong>http://&lt;yourservername&gt;:&lt;port&gt;/admin-panel/configuration</strong></p></div>
<div class="paragraph"><p>After restarting the server, admin panel would now also be accessible over SSL.
<strong>https://&lt;yourservername&gt;:&lt;port&gt;/admin-panel</strong></p></div>
</td>
</tr></table>
</div>
</div>
<div class="sect3">
<h4 id="_when_installing_with_rvm">3.2.2. When Installing with RVM</h4>
<div class="paragraph"><p>WebROaR gem can be installed with RVM using following command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rvmsudo webroar install</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="title">Failing Installation Known Issues</div>
<div class="listingblock">
<div class="content">
<pre><tt>Creating directory structure ... done.
Compiling C source files ... failed.
Compilation error. Please refer 'install.log' for details.</tt></pre>
</div></div>
<div class="paragraph"><p>This happens due to rake 0.9.2 executable taking priority over 0.8.7. A quick workaround involves temporarily removing the newer rake:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>gem list rake
gem uninstall rake
[choose 0.9.2]
gem install rake -v=0.8.7</tt></pre>
</div></div>
<div class="paragraph"><p>Re-run the installation script.</p></div>
</td>
</tr></table>
</div>
</div>
<div class="sect3">
<h4 id="_install_from_source_code">3.2.3. Install from source code</h4>
<div class="paragraph"><p>If you like living in the fast lane, you can install the edge version giving
the following commands:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>git clone git://github.com/webroar/webroar.git
cd webroar
sudo rake install</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="title">SSL Support</div>
<div class="paragraph"><p>To build with SSL support, use the following additional switch with the
<strong>sudo rake install</strong> command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo rake install ssl=yes</tt></pre>
</div></div>
<div class="paragraph"><p>Configure further SSL options in the server&#8217;s admin panel
        <strong>http://&lt;yourservername&gt;:&lt;port&gt;/admin-panel/configuration</strong></p></div>
<div class="paragraph"><p>After restarting the server, admin panel would now also be accessible over SSL.
<strong>https://&lt;yourservername&gt;:&lt;port&gt;/admin-panel</strong></p></div>
</td>
</tr></table>
</div>
</div>
<div class="sect3">
<h4 id="_non_interactive_install_using_capistrano">3.2.4. Non-Interactive Install using Capistrano</h4>
<div class="paragraph"><p>You can use following Capistrano script to install the edge version on a
remote machine</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Create folder &lt;dir&gt;, move to &lt;dir&gt; folder using <strong>cd &lt;dir&gt;</strong>.
</p>
</li>
<li>
<p>
Apply command <strong>capify .</strong>
</p>
</li>
<li>
<p>
Replace the content of <strong>config/deploy.rb</strong> with the following script
</p>
<div class="listingblock">
<div class="content">
<pre><tt>set :application, "WebROaR"
set :repository,  "git://github.com/webroar/webroar.git"

set :scm, :git

#############################################
# WebROaR installation parameters           #
#############################################
# Instead of asking for admin user name, password and port you can directly set
# it from here.

set :user, 'username'
set :port, 22
set(:password) { Capistrano::CLI.password_prompt("Enter ssh password for \
#{user}: ") }
set :use_sudo, false
set :deploy_to, "path-to-deploy-webroar"
set(:webroar_admin_username) { Capistrano::CLI.ui.ask("Please enter a username \
for the administrator account of server's admin panel:") }
set(:webroar_admin_password) { Capistrano::CLI.password_prompt("Please enter a \
password(minimum 6 characters) for the administrator account of server's admin \
panel:") }
set(:webroar_port) { Capistrano::CLI.ui.ask("Enter server port \
(default is 3000):") }
set :webroar_import_configuration, true # set false to beging with fresh install
set :webroar_ssl_support, false # set true to Build webroar with SSL support

role :web, "server"         # Your HTTP server, Apache/etc
role :app, "server"         # This may be the same as your `Web` server
role :db,  "server", :primary =&gt; true # This is where Rails migrations will run

############################################

namespace :deploy do
  # hook into capistrano's deploy task
  after 'deploy:update_code', 'deploy:webroar:install'

  task :finalize_update, :except =&gt; { :no_release =&gt; true } do
    run "chmod -R g+w #{release_path}" if fetch(:group_writable, true)
  end

  namespace :webroar do

    desc "Uninstall the webroar gem"
    task :uninstall do
      run "#{sudo} webroar uninstall; #{sudo} gem uninstall -ax webroar"
    end

    desc "Install the server"
    task :install, :roles =&gt; :app do
      run "cd #{release_path}; #{sudo} rake install #{'ssl=on' if \
      webroar_ssl_support}", :pty=&gt;true do |ch, stream, out|
        next if out.chomp == ''
        logger.important out, ch[:server]
        case out
          when / least/
          raise Capistrano::Error, out
          when /&gt;/
          ch.send_data("#{webroar_import_configuration ? '1' : '2'}\n")
          when / username/
          ch.send_data("#{webroar_admin_username}\n")
          when / password/
          ch.send_data("#{webroar_admin_password}\n")
          when / port/
          ch.send_data("#{webroar_port}\n")
        end
      end
    end


    desc "Start, Stop and Restat the server"
    %w(start stop restart).each do |name|
      task name.to_sym,:roles =&gt; :app do
        run "#{sudo} webroar #{name}"  #Manual Configuration required, this is best effort.
      end
    end

  end

end</tt></pre>
</div></div>
</li>
<li>
<p>
Set the variables in <strong>config/deploy.rb</strong> file.
</p>
</li>
<li>
<p>
To setup the fresh directory structure on the remote machine run
<strong>cap deploy:setup</strong>
</p>
</li>
<li>
<p>
To deploy the application for the first time run <strong>cap deploy:cold</strong>
  (Steps 1-6 are to be followed only once to create directory setup on remote
  machine.)
</p>
</li>
<li>
<p>
Update the current version with the latest code from github using
<strong>cap deploy:update</strong>.
</p>
</li>
</ol></div>
</div>
</div>
<div class="sect2">
<h3 id="_troubleshooting">3.3. Troubleshooting</h3>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/important.png" alt="Important" />
</td>
<td class="content">It is suggested that rubygems software should be setup correctly
beforehand, and you should be successfully able to access and use the already
installed gems. (If you use Ubuntu, you might be able to relate to this point
better.)</td>
</tr></table>
</div>
<div class="ulist"><ul>
<li>
<p>
In case auto-installation of dependent gems fails (due to some prehistoric
rubygems version or any other reason), you can install the following dependent
 gems individually first:
</p>
<div class="literalblock">
<div class="content">
<pre><tt>rails-3.0.9, rake, rspec, sqlite3, starling, will_paginate</tt></pre>
</div></div>
</li>
<li>
<p>
After successful installation of the webroar gem, any errors that occur
during the setup are saved to the install.log created in the installed gem&#8217;s
directory. This can be used to troubleshoot the issues, if any.
</p>
</li>
<li>
<p>
All run time logs for the server and the deployed applications can be found
in <strong>/var/log/webroar</strong>. In the unfortunate event of the server crashing, a core
dump file would be created in /tmp if <em>gcore</em> is available on that machine.
</p>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_setting_up_database_for_server_admin_panel">3.4. Setting up database for server admin panel</h3>
<div class="paragraph"><p>The server&#8217;s admin panel itself is a Ruby on Rails&#8482; web application, and by
default uses sqlite as it&#8217;s database. You can edit
<strong>admin_panel/config/database.yml</strong> to setup a database of your liking and
follow it up by running these commands from the <strong>admin_panel</strong> directory.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:create
rake db:migrate</tt></pre>
</div></div>
<div class="paragraph"><p><strong>admin_panel</strong> directory would be present under the server&#8217;s rubygem
directory.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage">4. Usage</h2>
<div class="sectionbody">
<div class="paragraph"><p>Start/Stop/Restart WebROaR:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar start
sudo webroar stop
sudo webroar restart</tt></pre>
</div></div>
<div class="paragraph"><p>Start/Stop/Restart a deployed application:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar start &lt;Application Name&gt;
sudo webroar stop &lt;Application Name&gt;
sudo webroar restart &lt;Application Name&gt;</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">
<div class="paragraph"><p>You can stop the admin panel application of the server any time, to conserve
resources and ensure better security.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar stop "Admin Panel"</tt></pre>
</div></div>
<div class="paragraph"><p>To start it whenever you want, use the following command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar start "Admin Panel"</tt></pre>
</div></div>
<div class="paragraph"><p>Please note that analytics data and exceptions are still captured by the
server even when the admin panel is stopped.</p></div>
</td>
</tr></table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_deploying_applications">5. Deploying applications</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_deploy_using_admin_panel">5.1. Deploy using Admin Panel</h3>
<div class="paragraph"><p>If the server got installed successfully, you should be able access it&#8217;s admin
panel using the link:<br />
<strong>http://&lt;yourservername&gt;:&lt;port&gt;/admin-panel</strong></p></div>
<div class="paragraph"><p>You can log in with the administrator account username and password that you
had entered during server installation. Deploy the ruby web application of
your choice accessing the <strong>Configuration</strong> link of the admin panel.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/tip.png" alt="Tip" />
</td>
<td class="content">You do <strong>"not"</strong> need to restart the server when you deploy a new application.
The application starts up automatically after deployment.</td>
</tr></table>
</div>
</div>
<div class="sect2">
<h3 id="_deploy_using_capistrano">5.2. Deploy using Capistrano</h3>
<div class="paragraph"><p>WebROaR can be easily integrated with Capistrano using the following
instructions.</p></div>
<div class="paragraph"><p>After installing Capistrano, run the following command in your application&#8217;s
root directory:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>capify .</tt></pre>
</div></div>
<div class="paragraph"><p>It would create <strong>Capfile</strong> and <strong>config/deploy.rb</strong> files.
Modify <strong>config/deploy.rb</strong> file as shown below:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>set :application, "myapp"

set :scm,:none
set :repository, "."

set :copy_cache, "/tmp/my-app"
set :copy_compression,:gzip
set :deploy_via,:copy
set :copy_exclude, [".git/*", "log/*", "Capfile", "config/deploy.rb", "*~", ".*"]

set :password, 'password'
set :use_sudo, false
set :user, 'username'
set :port, 22

set :deploy_to, "path-to-your-web-app-directory/#{application}"

################################
# Parameters used to add application to the server
################################
set :resolver, "/#{application.gsub(' ','_')}"
set :path, "#{deploy_to}/current"
set :app_type, "rails"
set :environment, "production"
set :analytics, "--analytics" # ' ' (blank) to disable analytics
set :min_workers, "4"
set :max_workers, "8"
set :run_as_user, "#{user}"
################################

role :app, "server"
role :web, "server"
role :db,  "server", :primary =&gt; true

#role :db,  "your slave db-server here"

namespace :deploy do

  [:stop, :start, :restart].each do |action|
    desc "#{action.to_s.capitalize} the application."
    task action, :roles =&gt; :app do
      run "#{sudo} webroar #{action.to_s} #{application.to_s}"
    end
  end

  desc "Add application to the server"
  task :add, :roles =&gt; :app do
    run "#{sudo} webroar add '#{application}' --resolver'#{resolver}' \
    --path'#{path}' -type'#{app_type}' -environment'#{environment}' #{analytics} \
    --min-workers#{min_workers} --max-workers#{max_workers} \
    --run-as-user'#{run_as_user}'"
  end

  desc "Remove application from the server"
  task :remove, :roles =&gt; :app do
    run "#{sudo} webroar remove '#{application}'"
  end

end

after "deploy:update",  "deploy:restart"</tt></pre>
</div></div>
<div class="paragraph"><p>Create the application directory structure by running setup command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>cap deploy:setup</tt></pre>
</div></div>
<div class="paragraph"><p>Deploy the application using command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>cap deploy</tt></pre>
</div></div>
<div class="paragraph"><p>Add the application to WebROaR:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>cap deploy:add</tt></pre>
</div></div>
<div class="paragraph"><p>Please note that the application needs to be added to the server only once.</p></div>
<div class="paragraph"><p>You can use the following commands for starting/stopping/restarting the
application while upgrading it in the future:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>cap deploy:stop
cap deploy:start
cap deploy:restart</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_rack_applications_other_than_rails">5.3. Rack applications (other than Rails)</h3>
<div class="paragraph"><p>To deploy any Rack based application (other than Rails) the following are
required in it&#8217;s root directory:</p></div>
<div class="ulist"><ul>
<li>
<p>
<strong>public</strong> folder containing static files like images and stylesheets
</p>
</li>
<li>
<p>
<strong>config.ru</strong> - the Rackup file for starting the application. This file must
contain the complete logic for initializing the application.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Here are some examples of the Rackup files:</p></div>
<div class="paragraph"><p><strong>Merb</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  require 'rubygems'
  require 'merb-core'
  Merb::Config.setup(:merb_root   =&gt; ENV['APP_ROOT'],
                     :environment =&gt; ENV['APP_ENV'],
                     :path_prefix =&gt; ENV['APP_BASE_URI'])
  Merb.environment = Merb::Config[:environment]
  Merb.root = Merb::Config[:merb_root]
  Merb::BootLoader.run
  run Merb::Rack::Application.new</tt></pre>
</div></div>
<div class="paragraph"><p><strong>Sinatra</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><tt>  require 'rubygems'
  require 'rack'
  require 'sinatra'
  set :env, ENV['APP_ENV'] || :production
  set :raise_errors, true
  run Sinatra::Application</tt></pre>
</div></div>
<div class="paragraph"><p>You can use following environment variables in <strong>config.ru</strong> to access the few
application configuration parameters given at a time of application deployment
in WebROaR.</p></div>
<div class="ulist"><ul>
<li>
<p>
ENV['APP_ROOT\'] - To get the application root
</p>
</li>
<li>
<p>
ENV['APP_ENV\'] - To get the application environment
</p>
</li>
<li>
<p>
ENV['APP_BASE_URI\'] - To get the baseuri
</p>
</li>
</ul></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_accessing_run_time_statistics">6. Accessing run time statistics</h2>
<div class="sectionbody">
<div class="paragraph"><p>For those applications whose Analytics are <strong>Enabled</strong> in their configuration,
the following graphs are available under the <strong>Analytics</strong> link of the admin panel.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
URL Breakdown
</p>
</li>
<li>
<p>
Most Time Consuming URLs
</p>
</li>
<li>
<p>
URL Hits
</p>
</li>
<li>
<p>
Slowest URLs
</p>
</li>
<li>
<p>
Top Database Consuming URLs
</p>
</li>
<li>
<p>
Percentage Time Spent in Database Layer
</p>
</li>
<li>
<p>
Average Response Time
</p>
</li>
<li>
<p>
Peak Requests in Second
</p>
</li>
<li>
<p>
Percentage CPU Utilization
</p>
</li>
<li>
<p>
Physical Memory Utilization
</p>
</li>
</ol></div>
<div class="paragraph"><p>Additionally, CPU and Physical Memory usage graphs for the entire server are
also available.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">Currently, Analytics are only supported for Ruby on Rails&#8482; applications.
Also, after a specific request has been processed by the server, it takes
about a minute for it’s data to show up in the graphs.</td>
</tr></table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_exception_tracking_and_notifications">7. Exception Tracking and Notifications</h2>
<div class="sectionbody">
<div class="paragraph"><p>Any exceptions that occur in any of the deployed application are captured by
the server. An email notification is also sent out immediately with details of
the exception, if the mail settings have been configured in the admin panel.</p></div>
<div class="paragraph"><p>All the exceptions can be seen under the <strong>Exceptions</strong> link of the server admin
panel.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="./images/icons/note.png" alt="Note" />
</td>
<td class="content">Currently, this feature is only supported for Ruby on Rails&#8482; applications.
Also, it takes about a minute for an exception to show up in the Admin Panel
after it has occurred.</td>
</tr></table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_uninstall">8. Uninstall</h2>
<div class="sectionbody">
<div class="paragraph"><p>If you didn&#8217;t like the server, use the following commands in sequence to
uninstall it.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar uninstall
sudo gem uninstall webroar</tt></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_test_suite">9. Test Suite</h2>
<div class="sectionbody">
<div class="paragraph"><p>If you are a programmer and wish to play around with the server&#8217;s code, you
might like to use it&#8217;s test suite to test the robustness of your changes.</p></div>
<div class="paragraph"><p>It can be run using the following command:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>sudo webroar test</tt></pre>
</div></div>
<div class="paragraph"><p>We execute this suite on our nightly builds and it currently has the following
tests:</p></div>
<div class="ulist"><ul>
<li>
<p>
Unit Tests
</p>
</li>
<li>
<p>
Functional Tests
</p>
</li>
<li>
<p>
Admin-Panel Tests
</p>
</li>
<li>
<p>
Load Test I - Continuous run
</p>
</li>
<li>
<p>
Load Test II - Random sleep interval run
</p>
</li>
<li>
<p>
Build Tests
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_command_line_options">10. Command Line Options</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_webroar_help">10.1. webroar help</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar [-v | --version] [-h | --help] COMMAND [ARGS]

  The available webroar commands are:
    install       Install the server
    uninstall     Uninstall the server
    start         Start the server or an application
    stop          Stop the server or an application
    restart       Restart the server or an application
    add           Deploy an application on the server
    remove        Remove an application from the server
    test          Run the test suite

  For help on a particular command, use 'webroar help COMMAND'.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_install">10.2. webroar install</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar install [-s] [ -L&lt;library path&gt;] [ -I&lt;include path&gt;] [-d] [ -i |
                    [ --no-import] [ -P&lt;port&gt;] [ -u&lt;user&gt;] [-p&lt;password&gt;] ]

  Options:
    -L
        Additional library paths to be used for linking of the server

    -I
        Additional include paths to be used for linking of the server

    -s, --ssl-support
        Install the server with SSL support

    -d, --debug-build
        Compile the server as a debug build to output extremely verbose logs

  The following options would make the install non-interactive by suppressing
  the questions prompted by the installer

    -P, --port
        Server port number

    -i, --import
        Import configuration, logs and admin panel data from the previous
        installation

    --no-import
        Do not import configuration, logs and admin panel data from the previous
        installation

    -u, --username
        Username for the administrator account of server's admin panel

    -p, --password
        Password for the administrator account of server's admin panel

  Summary:
    Install the server</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_uninstall">10.3. webroar uninstall</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar uninstall

  Summary:
    Uninstall the server</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_start">10.4. webroar start</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar start [&lt;app(s)&gt;]

  Arguments:
    &lt;app(s)&gt;
        Name of the application(s)

  Summary:
    Start the server or an application

  Description:
    'start' command without any arguments starts the server. One can start
    multiple applications together by passing multiple names.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_stop">10.5. webroar stop</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar stop [&lt;app(s)&gt;]

  Arguments:
    &lt;app(s)&gt;
        Name of the application(s)

  Summary:
    Stop the server or an application

  Description:
    'stop' command without any arguments stops the server. One can stop
    multiple applications together by passing multiple names.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_restart">10.6. webroar restart</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar restart [&lt;app(s)&gt;]

  Arguments:
    &lt;app(s)&gt;
        Name of the application(s)

  Summary:
    Restart the server or an application

  Description:
    'restart' command without any arguments restarts the server. One can
    restart multiple applications together by passing multiple names.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_add">10.7. webroar add</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar add [&lt;app&gt;] [ -R] [ -D] [ -U] [ -T] [ -E] [ -A] [ -N] [ -X]

  Arguments:
    &lt;app&gt;
        Name of the application

  Options:
    The following parameters are mandatory, if the current directory would not
    be the Rails or Rack root directory

    -R, --resolver
        Resolver to identify the application. Set it to '/' if you would like
        to run the application on the root domain. e.g. http://yourserver:port/.
        (default: /&lt;app&gt;)

        Else set the relevant base URI with which you would like to access the
        application, e.g. '/app1' if you want the application to be accessible
        via http://yourserver:port/app1.

        If you would like to set a virtual host for your application e.g.
        www.company1.com, please specify it here. You can also host this
        application on a particular subdomain e.g. app1.company1.com. Wildcard
        '*' can also be used in defining the virtual host name, but it should
        only be used either at the start or the end. Prefix the virtual host
        name with tilde(~), if a wildcard is used in defining it.
        e.g. (i) ~*.server.com (ii) ~www.server.* (iii) ~*.server.*

    -D, --path
        Complete path for your application root directory: e.g. /home/someuser/webapps/app1
        (default: current directory)

    -U, --run-as-user
        Name of the user with whose privileges you would like to run the
        application (root can be dangerous!). This user should have all the
        necessary permissions to get your web application working properly
        (e.g. write access on required files and directories etc)
        (default: Owner of 'config/environment.rb' or 'config.ru' file)

    The following parameters are optional

    -T, --type
        Type of the application either rack or rails (default: rails)

    -E, --environment
        Environment in which you want to run the application (default: production)

    -A, --analytics
        Enable analytics to get detailed numbers about the run time performance
        of the application. This number gathering adds a very small overhead on
        your application

    -N, --min-workers
        Minimum number of worker processes that should run for this deployed
        application. Multiple worker instances help in processing a higher number
        of concurrent user requests simultaneously. The server would always
        ensure at least these many worker processes run for this application
       (default: 4)

    -X, --max-workers
        Maximum number of worker processes that should run for this deployed
        application. Multiple worker instances help in processing a higher
        number of concurrent user requests simultaneously. The server would
        ensure that maximum only these many worker processes run for this
        application (default: 8)

  Summary:
    Deploy (and start) a new application on the server.

  Description:
    If application name is not passed, it would look for 'config/environment.rb'
    or 'config.ru' file in the current directory. If any one of the files found,
    it passes name of the current directory as an application name.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_remove">10.8. webroar remove</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar remove [&lt;app&gt;]

  Arguments:
    &lt;app&gt;
        Name of the application

  Summary:
    Remove the specified application from the server.

  Description:
    If application name is not passed, it would look for 'config/environment.rb'
    or 'config.ru' file in the current directory. If any one of the files found,
    it passes name of the current directory as an application name.</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_webroar_test">10.9. webroar test</h3>
<div class="listingblock">
<div class="content">
<pre><tt>  Usage:
    webroar test [ -r&lt;report dir&gt;] [ -d] [ -l]

  Options:
    -r, --report-dir
        Report directory

    -d, --debug-build
        Compile the server as a debug build to output extremely verbose logs

    -l, --load-test
        Also run the load tests

  Summary:
    Run the test suite</tt></pre>
</div></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2011-12-14 12:58:59 IST
</div>
</div>
</body>
</html>
